<p>
    Allows various kinds of credentials (secrets) to be used in idiosyncratic ways.
    (Some steps explicitly ask for credentials of a particular kind,
    usually as a <code>credentialsId</code> parameter,
    in which case this step is unnecessary.)
    Each binding will define an environment variable active within the scope of the step.
    You can then use them directly from any other steps that expect environment variables to be set:
</p>
<pre><code>node {
  withCredentials([usernameColonPassword(credentialsId: 'mylogin', variable: 'USERPASS')]) {
    sh '''
      set +x
      curl -u "$USERPASS" https://private.server/ > output
    '''
  }
}</code></pre>
<p>
    As another example (use <i>Snippet Generator</i> to see all options):
</p>
<pre><code>node {
  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
    sh '''
      set +x
      curl -H "Token: $TOKEN" https://some.api/
    '''
  }
}</code></pre>
<p>
    Note the use of <em>single</em> quotes to define the <code>script</code>
    (implicit parameter to <code>sh</code>) in Groovy above.
    You want the secret to be expanded by the shell as an environment variable.
    The following idiom is potentially less secure, as the secret is interpolated by Groovy
    and so (for example) typical operating system process listings will accidentally disclose it:
</p>
<pre><code>node {
  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
    sh /* WRONG! */ """
      set +x
      curl -H 'Token: $TOKEN' https://some.api/
    """
  }
}</code></pre>
<p>
    At least on Linux, environment variables can be obtained by other processes running in the same account,
    so you should not run a job which uses secrets on the same node as a job controlled by untrusted parties.
    In any event, you should always prefer expansion as environment variables to inclusion in the command,
    since Jenkins visualizations such as Blue Ocean will <em>attempt</em> to detect step parameters containing secrets
    and refuse to display them.
</p>
<p>
    The secret(s) will be masked (<code>****</code>) in case they are printed to the build log.
    This prevents you from <em>accidentally</em> disclosing passwords and the like via the log.
    (Bourne shell <code>set +x</code>, or Windows batch <code>@echo off</code>,
    blocks secrets from being displayed in echoed commands;
    but build tools in debug mode might dump all environment variables to standard output/error,
    or poorly designed network clients might display authentication, etc.)
    The masking could of course be trivially circumvented;
    anyone permitted to configure a job or define Pipeline steps
    is assumed to be trusted to use any credentials in scope however they like.
</p>
<p>
    Beware that certain tools mangle secrets when displaying them.
    As one example, Bash (as opposed to Ubuntu’s plainer Dash) does so with text containing <code>'</code> in echo mode:
</p>
<pre><code>$ export PASS=foo"'"bar
$ env|fgrep PASS
PASS=foo'bar
$ sh -xc 'echo $PASS'
+ echo foo'bar
foo'bar
$ bash -xc 'echo $PASS'
+ echo 'foo'\''bar'
foo'bar
</code></pre>
<p>
    Mangled secrets can only be detected on a best-effort basis. By default, Jenkins will attempt to mask mangled
    secrets as they would appear in output of Bourne shell, Bash, Almquist shell and Windows batch. Without these strategies in place, mangled secrets
    would appear in plain text in log files. In the example above, this would result in:
</p>
<pre><code>+ echo 'foo'\''bar'
****</code></pre>
<p>
    This particular issue can be more safely prevented by turning off echo with <code>set +x</code> or avoiding the use
    of shell metacharacters in secrets.
</p>
<p>
    For bindings which store a secret file, beware that
</p>
<pre><code>node {
  dir('subdir') {
    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
      sh 'use $FILE'
    }
  }
}</code></pre>
<p>
    is not safe, as <code>$FILE</code> might be inside the workspace (in <code>subdir@tmp/secretFiles/</code>),
    and thus visible to anyone able to browse the job’s workspace.
    If you need to run steps in a different directory than the usual workspace, you should instead use
</p>
<pre><code>node {
  withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
    dir('subdir') {
      sh 'use $FILE'
    }
  }
}</code></pre>
<p>
    to ensure that the secrets are outside the workspace; or choose a different workspace entirely:
</p>
<pre><code>node {
  ws {
    withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
      sh 'use $FILE'
    }
  }
}</code></pre>
<p>
    Also see the
    <a href="https://jenkins.io/blog/2019/02/21/credentials-masking/" target="_blank">Limitations of Credentials Masking</a>
    blog post for more background.
</p>
